Skip to content

docs: avoid hyphen usage #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: avoid hyphen usage #85

wants to merge 3 commits into from

Conversation

maltehain
Copy link

Description

Remove hyphen in writing and therefore remove incorrect space between hyphen and "komponenten"

Motivation

I stumbled across this writing style and think with my proposed change it is more accurate and the reading experience will be increased.

Additional details

not applicable

Related issues and pull requests

not applicable

remove hyphen in writing and therefore remove incorrect space between hyphen and "komponenten"
Copy link

This pull request has merge conflicts that must be resolved before it can be merged.

@maltehain
Copy link
Author

Failed lint check does not related to changed file in the pull request

@caugner
Copy link
Contributor

caugner commented May 15, 2025

Hi @maltehain, thanks for taking the time to submit this PR. 🙌

Please note that the German content is automatically translated with GPT-4o, so merging your suggested changes will only resolve the problem until the page is translated again (as soon as the original English page is modified).

So for transparency, here is the full prompt for this page (click to expand)

(This is basically the content of the original file, with the YAML frontmatter replaced by a h1 heading, preceded by our translation prompt.)

You are tasked with translating MDN Web Docs content from English to German.

Ensure that the translation is accurate, preserves technical terminology, and follows the rules provided below.

# Rules for Translation

1. Format:

   - The input is a Markdown file.
   - The output should be a Markdown file.
   - Return the raw output, without wrapping it in a Markdown code block.
   - Keep GFM alert syntax untranslated, such as `> [!NOTE]`, `> [!WARNING]`, and `> [!CALLOUT]`.
   - If the input contains HTML tags wrapped in backticks (e.g. `<video>`), make sure they are wrapped in the output.
   - If the input contains HTML tags escaped with a slash (e.g. `\<length>`), make sure they are escaped in the output.

2. Language:

   - Prefer formal language ("Sie") over informal language ("du").

3. Code blocks:

   - Do not translate code blocks.
   - Do not translate terms wrapped in backticks.

4. Macro calls:

   - MDN uses macros for dynamic content insertion. These macros must remain **unchanged** and not translated.
   - Macro calls start with `{{`, followed by the macro name, optional parameters, and end with `}}`.
   - Avoid invalid macro calls by ensuring curly braces, parentheses, and quotes are closed properly.

5. Technical terms and code snippets in text:

   - Keep technical terms like element names, attributes, and method names in **English**. Only translate the surrounding descriptive text.

6. Links and References:

   - Translate link descriptions, but keep the URLs and their structure intact.
   - Do not change the locale in URLs.

7. Glossary:

   - "Browser compatibility" => "Browser-Kompatibilität"
   - "Guide" => "Leitfaden"
   - "How to" => "Anleitung"

# Translation Scope

Translate the following Markdown content from **English** to **German** while adhering to the rules above.

```md
# Browser extensions

{{AddonSidebar}}

Extensions, or add-ons, can modify and enhance the capability of a browser. Extensions for Firefox are built using the WebExtensions API cross-browser technology.

The technology for extensions in Firefox is, to a large extent, compatible with the [extension API](https://developer.chrome.com/docs/extensions/reference/) supported by Chromium-based browsers (such as Google Chrome, Microsoft Edge, Opera, Vivaldi). In most cases, extensions written for Chromium-based browsers run in Firefox with [just a few changes](https://extensionworkshop.com/documentation/develop/porting-a-google-chrome-extension/).

## Key resources

- Guides
  - : Whether you're just beginning or looking for more advanced advice, learn about how extensions work and use the WebExtensions API from our extensive range of [tutorials and guides](/en-US/docs/Mozilla/Add-ons/WebExtensions/What_are_WebExtensions).
- References
  - : Get comprehensive details about the methods, properties, types, and events of the [WebExtensions APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs) and full details about the [manifest keys](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json).
- Firefox workflow
  - : Discover how to build and publish extensions for Firefox: get the lowdown on developer tools, publication and distribution, and porting on [Extension Workshop](https://extensionworkshop.com/).

> [!NOTE]
> If you have ideas or questions or need help, you can reach us on the [community forum](https://discourse.mozilla.org/c/add-ons/35) or in the [Add-ons Room](https://matrix.to/#/!CuzZVoCbeoDHsxMCVJ:mozilla.org?via=mozilla.org&via=matrix.org&via=humanoids.be) on [Matrix](https://wiki.mozilla.org/Matrix).

## Get started

Discover [what extensions can do](/en-US/docs/Mozilla/Add-ons/WebExtensions/What_are_WebExtensions) before building [your first extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension) and [your second extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension). Learn about the [anatomy of an extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension) and get an overview of the [extension development and publication workflow, Firefox style](https://extensionworkshop.com/documentation/develop/firefox-workflow-overview/). Explore a little deeper with a comprehensive selection of [example extensions](/en-US/docs/Mozilla/Add-ons/WebExtensions/Examples) that you can run right in Firefox. Continue your learning by [discovering a list of resources](/en-US/docs/Mozilla/Add-ons/WebExtensions/What_next) to follow.

## Concepts

Get detailed information on the concepts that underpin extensions.

- [Overview of the JavaScript API](/en-US/docs/Mozilla/Add-ons/WebExtensions/API)
- [Content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts)
- [Background scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Background_scripts)
- [Match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns)
- [Working with files](/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_files)
- [Internationalization](/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization)
- [Content security policy](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy)
- [Native messaging](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging)
- [Native manifests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests)
- [User actions](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions)
- [Differences between API implementations](/en-US/docs/Mozilla/Add-ons/WebExtensions/Differences_between_API_implementations)
- [Chrome incompatibilities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities)

## User interface

Discover all the [user interface](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface) components you can use in your extensions, with coding examples and tips.

## How to

A range of tutorials to get you started on specific aspects of extension development.

- [Intercept HTTP requests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Intercept_HTTP_requests)
- [Modify a web page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Modify_a_web_page)
- [Safely insert external content into a page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Safely_inserting_external_content_into_a_page)
- [Share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts)
- [Add a button to the toolbar](/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar)
- [Implement a settings page](/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page)
- [Work with the Tabs API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Working_with_the_Tabs_API)
- [Work with the Bookmarks API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Bookmarks_API)
- [Work with the Cookies API](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_the_Cookies_API)
- [Work with contextual identities](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities)
- [Interact with the clipboard](/en-US/docs/Mozilla/Add-ons/WebExtensions/Interact_with_the_clipboard)
- [Extend the developer tools](/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools)
- [Build a cross-browser extension](/en-US/docs/Mozilla/Add-ons/WebExtensions/Build_a_cross_browser_extension)

## Firefox workflow

When you are ready to create your extension for Firefox or port your Chrome extension, head over to [Extension Workshop](https://extensionworkshop.com/). It has details on:

- The Firefox workflow, such as [temporarily installing extensions during development](https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/), [debugging](https://extensionworkshop.com/documentation/develop/debugging/), [request the right permissions](https://extensionworkshop.com/documentation/develop/request-the-right-permissions/), and more.
- The [web-ext](https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/) developer tool.
- [Porting a Google Chrome extension](https://extensionworkshop.com/documentation/develop/porting-a-google-chrome-extension/), [differences between desktop and Android](https://extensionworkshop.com/documentation/develop/differences-between-desktop-and-android-extensions/), and more.
- [Publishing and distribution overview](https://extensionworkshop.com/documentation/publish/), [promoting your extension](https://extensionworkshop.com/documentation/publish/promoting-your-extension/), the [extension lifecycle best practices](https://extensionworkshop.com/documentation/manage/), and more.

## Reference

### JavaScript APIs

Get comprehensive details about the methods, properties, types, and events for all the [JavaScript APIs](/en-US/docs/Mozilla/Add-ons/WebExtensions/API). There is also detailed information about the compatibility of each API with the major browsers. Most reference pages also include coding examples and links to the extension examples that use the API.

### Manifest keys

Get full details about the [manifest keys](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json), including all their properties and settings.
```

I just tried that prompt in ChatGPT with GPT-4o, and the result aligns with your suggestion:

Entdecken Sie alle Komponenten der Benutzeroberfläche, die Sie in Ihren Erweiterungen verwenden können, mit Codebeispielen und Tipps.

However, ChatGPT uses a different model than we use, and I just ran the translation pipeline for this page locally:

  1. With gpt-4o-2024-08-06 (which we're currently using), the result is:

    Entdecken Sie alle Benutzeroberflächen-Komponenten, die Sie in Ihren Erweiterungen verwenden können, mit Codebeispielen und Tipps.

  2. With gpt-4o-2024-11-20 (which we found to produce lower quality translations with our current prompt), the result is:

    Entdecken Sie alle Benutzeroberflächen-Komponenten, die Sie in Ihren Erweiterungen verwenden können, mit Beispielcode und Tipps.

  3. With gpt-4.1-2025-04-14 (the newest model, which we haven't evaluated yet), the result is:

    Entdecken Sie alle Benutzeroberflächen- Komponenten, die Sie in Ihren Erweiterungen nutzen können, inklusive Programmierbeispielen und Tipps.

It looks like both gpt-4o models no longer return the spaces around the hyphen, but this could be luck. On the other hand, they consistently translate "user interface components" with "Benutzeroberflächen-Komponenten", not "Komponenten der Benutzeroberfläche".

To improve the translations consistently, we likely need to adjust the prompt, essentially telling the LLM to avoid the spaces around the hyphen for compound terms, and potentially prefer "Komponenten der Benutzeroberflächen" over "Benutzeroberflächen-Komponenten" for longer words (which could be trickier to prompt).

However, changing the prompt can have unintended side-effects on other parts of the translation.

So here's what I suggest: Could you please create an issue for this, and check for other instances of this problem (e.g. search for /) - /)? 🙏

PS: I invite you to join the #german channel on our Discord server to further discuss.

Copy link

This pull request has merge conflicts that must be resolved before it can be merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants